home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3dm / audio / alGetParams.z / alGetParams
Encoding:
Text File  |  1998-10-20  |  7.6 KB  |  199 lines
  1.  
  2.  
  3.  
  4. aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))                                              aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alGetParams - get the values of audio resource parameters
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  13.  
  14.      iiiinnnntttt aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((iiiinnnntttt rrrreeeessssoooouuuurrrrcccceeee,,,, AAAALLLLppppvvvv ****ppppvvvvssss,,,, iiiinnnntttt nnnnppppvvvvssss))))
  15.  
  16. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  17.      _r_e_s_o_u_r_c_e
  18.             expects the resource from which you wish to get parameter values.
  19.  
  20.      _p_v_s    is an array of ALpv structures, each of which contains a single
  21.             parameter and will contain the associated value upon return from
  22.             aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss.
  23.  
  24.      _n_p_v_s   is the number of ALpv items in the array.
  25.  
  26. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  27.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss acquires the current values for a set of parameters from a
  28.      specific audio resource.
  29.  
  30.      Each parameter/value pair is represented by a single ALpv structure:
  31.  
  32.           typedef struct {
  33.               int     param;          /* parameter */
  34.               ALvalue value;          /* value */
  35.               short   sizeIn;         /* size in -- 1st dimension */
  36.               short   size2In;         /* size out -- 2nd dimension */
  37.               short   sizeOut;        /* size out */
  38.               short   size2Out;        /* size out -- 2nd dimension */
  39.           } ALpv;
  40.  
  41.  
  42.      The application should set the _p_a_r_a_m field in each ALpv to indicate which
  43.      parameter is of interest.
  44.  
  45.      For scalar parameters, this is sufficient; aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss will fill in the
  46.      corresponding _v_a_l_u_e field.
  47.  
  48.      For non-scalar parameters, the application is responsible for allocating
  49.      the memory required to hold the value. In addition to setting _p_a_r_a_m, the
  50.      application must set the pointer field of _v_a_l_u_e (value.ptr) to point to
  51.      the allocated buffer, and set _s_i_z_e_I_n to indicate the size of the buffer,
  52.      in elements. aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss will write the value to the given buffer,
  53.      filling in at most _s_i_z_e_I_n elements.
  54.  
  55.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss will set the _s_i_z_e_O_u_t field of each ALpv to indicate how many
  56.      elements it returned. For valid scalar parameters, this is always 1.  For
  57.      non-scalar parameters, it return the number of elements available, even
  58.      if greater than _s_i_z_e_I_n. For any parameter, it can also set _s_i_z_e_O_u_t to a
  59.      negative value to indicate an error with that particular parameter.
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))                                              aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      alGetParams currently supports only one negative _s_i_z_e_O_u_t value:
  75.      AL_INVALID_PARAM, which indicates that the given parameter was
  76.      unrecognized by the given resource.
  77.  
  78.      See the aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) man page for more information on the semantics of
  79.      particular parameters.
  80.  
  81. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  82.      The following code fragment gets the value of the sample rate, the gain,
  83.      and the name of the default audio input device.
  84.  
  85.           int  i;
  86.           ALpv      pvs[3];
  87.           char      name[32];
  88.           ALfixed gain[8];
  89.  
  90.           pvs[0].param = AL_RATE;       /* a scalar parameter */
  91.  
  92.           pvs[1].param = AL_GAIN;       /* a vector parameter */
  93.           pvs[1].value.ptr = gain; /* the vector we've allocated */
  94.           pvs[1].sizeIn = 8;       /* the number of elements in gain */
  95.  
  96.           pvs[2].param = AL_NAME;       /* a string parameter */
  97.           pvs[2].value.ptr = name; /* the string we've allocated */
  98.           pvs[2].sizeIn = 32;      /* the array size, in characters,
  99.                                  including space for NULL */
  100.  
  101.           /*
  102.            * Now we ask the default input device for its sample rate, name,
  103.            * and current input gain. Note that there's nothing input-specific
  104.            * about this code. To use a default output device, we simply supply
  105.            * AL_DEFAULT_OUTPUT as the resource to alGetParams.
  106.            */
  107.           if (alGetParams(AL_DEFAULT_INPUT, pvs, 3) < 0) {
  108.               printf("alGetParams failed: %s\n", alGetErrorString(oserror()));
  109.           }
  110.  
  111.           printf("name is %s, rate is %lf\n",
  112.               name, alFixedToDouble(pvs[0].value.ll));
  113.  
  114.           for (i = 0; i < pvs[1].sizeOut; i++) {
  115.               printf("gain[%d] = %lf dB\n", alFixedToDouble(gain[i]));
  116.           }
  117.  
  118.  
  119. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  120.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss returns the number of recognized parameters in the given PV
  121.      list. It can also return a negative value, and set an error code, to
  122.      indicate errors with the entire _a_l_G_e_t_P_a_r_a_m_s call. In this case, the error
  123.      code retrieved by oooosssseeeerrrrrrrroooorrrr((((3333CCCC)))) will be one of:
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))                                              aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm))))
  137.  
  138.  
  139.  
  140.      AAAALLLL____BBBBAAAADDDD____PPPPVVVVBBBBUUUUFFFFFFFFEEEERRRR
  141.           _p_v_s is invalid.
  142.  
  143.      AAAALLLL____BBBBAAAADDDD____BBBBUUUUFFFFFFFFEEEERRRRLLLLEEEENNNNGGGGTTTTHHHH
  144.           _n_p_v_s is patently wrong (e.g. negative).
  145.  
  146.      AAAALLLL____BBBBAAAADDDD____DDDDEEEEVVVVIIIICCCCEEEE____AAAACCCCCCCCEEEESSSSSSSS
  147.           The audio system is inaccessible, either because it is not installed
  148.           on the system, or because it is incorrectly configured.
  149.  
  150.      AAAALLLL____BBBBAAAADDDD____RRRREEEESSSSOOOOUUUURRRRCCCCEEEE
  151.           The given resource _r_e_s_o_u_r_c_e does not exist.
  152.  
  153. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  154.      alParams(3dm), alSetParams(3dm), alGetParamInfo(3dm), oserror(3C)
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.